LoadIconCache

LoadIconCache
Header:	Icons.h		Carbon status:	Supported

Loads into an icon cache a handle to the appropriate icon data for a specified destination rectangle and the current bit depth, for drawing later with a specified alignment and transform.

OSErr LoadIconCache (
    const Rect *theRect, 
    IconAlignmentType align, 
    IconTransformType transform, 
    IconCacheRef theIconCache
);

theRect: A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The function uses the rectangle specified in this parameter and the bit depth of the display device to determine which icon type to load into the cache.
align: Specifies how to align the icon within the rectangle. See “Alignment Type Values” for a description of the values you can use in this parameter.
transform: Specifies how to modify the appearance of the icon. See “Transform Type Values” for a description of the values you can use in this parameter.
theIconCache: A handle to the icon cache into which to load the icon data.

function result: A result code.

DISCUSSION

This function can be useful, for example, if you suspect that the icon may be drawn at a time not convenient for loading resource data (for instance, when the resource fork isn’t in the current resource chain). The function uses the same criteria as the PlotIconSuite function to select the icon to load.

This function uses the icon getter callback function associated with the icon cache to get the appropriate icon. The icon getter function returns a handle to the requested icon data, and LoadIconCache adds the returned handle to the entry for that icon in the icon cache.

After calling this function, you can pass the same parameters to PlotIconSuite to plot the icon data. Note that if you specify an alignment when you call LoadIconCache, then call PlotIconSuite and specify no alignment, PlotIconSuite draws the icon using the alignment that you originally specified to LoadIconCache.

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.